rgb1440

ABZmonPPC
a native PowerPC Debugger
by Alain Birtz
version 0.9
Reference manual

Alain Birtz
650 Grand St-Charles,
St-Paul d’Abbotsford,
P.Q., Canada, J0E-1A0
CompuServe: [72467,2770]
Internet: 72467.2770@compuserve.com

lainA typical ABZmonPPC debugger screen

	

ABZmonPPC folder

The ABZmonPPC folder holds six items: the English and Frenchdocumentation, an important ReadMe text, the ABZmonPPC_ƒ folderholding the debugger INIT and the ABZmonPPC.help, PPCdebKey_ƒfolder holding a programmer swtich INIT and it documentation file, and test_deb_f folder holding a native application to test the debugger andall assembler source file needed to rebuild the application in MPW.ABZmonPPC can be distributed freely, but please, keep the files together.

Installation

To install the monitor put the 'ABZmonPPC', ABZmonPPC .help andPPCdebKey into the Extension folder or into System folder and restart thecomputer. ABZmonPPC and ABZmonPPC.help must be in the same folder. If themonitor is correctly loaded you will see this icon at the bottom of thescreen:

As soon as you see the monitor icon, the monitor is active, and youcan call the monitor immediately (for example, to check how other INITs areinstalled).

Note: the icon symbol is the one found on some Mac interrupt switch...

If the monitor is not correctly loaded you will see this icon:

You can disable the loading process by pressing the 'Option' and =keys  at the startup.

Warning: Pre-System 7.5 must use PPCTraceEnabler extension,otherwise trace and step doesn't work correctly in ABZmonPPC.PPCTraceEnabler is not needed for System 7.5 or higher
Presentation

ABZmonPPC is a low level debugger, a tool to check programming errors.Like other debuggers, ABZmonPPC has standard features such as a breakpoint, a step by step mode, a memory dump, a  microprocessor register dump,etc.

But ABZmonPPC has many other functions usually not found in otherdebuggers. For example, ABZmonPPC has a graphical interface using windows,menus and a mouse. A text can be viewed inside the debugger. You can quit a"frozen" application and continue normally with another application.

Many functions have been added to ABZmonPPC to help the programmer.Inside a code window, for example, you can see an operand, let's say apointer  like $4(r1), directly by option-clicking on the operand. In thisexample , you can see the pointer's address but also the pointed value. Youcan save the address (inside the CLIP buffer) and with a simple mouseclick, you can open a code or memory dump at this address.

The user can choose the part of the screen where ABZmonPPC will bedisplayed. The debugger image can be moved on the screen within thedebugger, and ABZmonPPC now support color. A second video monitor can bedevoted to the debugger. An ABZmonPPC's screen snapshot can be taken withjust a key combination.

You can set more than fifty internal parameters, including exceptionvectors, that controls the way  ABZmonPPC works. You can save your menu andwindow setups for the next time. You can also save the useful addresses orvalues of the CLIP buffer.

ABZmonPPC is the native port of ABZmon  (the low level debugger for68000 microprocessor family) for PowerPC microprocessor. ABZmonPPC
is entirely written in PowerPC assembler.

Since the PowerMac run 68020 program, ABZmonPPC can also work haslow level debugger for 68020 processor. ABZmonPPC support standard 68Kdebugger feature such break point, single step, n-step, line-A trapintercept, etc. However, ABZmonPPC is built for PowerPC, so feature for 68Kare limited to the basic one...

How the debugger is invoked

The debugger appear when:

-  in your code, you insert one of the Debug instruction. The debuggerstops  the program after the instruction.

-  you set a break point. The debugger stops  the program at theinstruction under the break point. The instruction is not executed

-  a step/trace command is given.

-  a stop condition is meet. A such condition appear in the "Stop"menu: changes in some memory segment, register taking some value, programexeciting  a given instruction.

-  on a bus error, address error, illegal instruction, etc...

-  some Mac have a programmer switch. Hitting this button induce a NMIexception. ABZmonPPC is enterred when the 68K NMI vector is set (defaultsetting).

-  the programmer key is hit. 'PPCdebKey' is a little extension thatset the programmer key to control-` (or control-~). 'PPCdebKey' isincluded in the ABZmonPPC folder. Resume with a GO command.

ABZmonPPC graphic interface

The ABZmon's graphic's  interface is similar to the Mac's graphic'sinterface, but it is not identical. In fact the debugger doesn't use anyQuickDraw procedures. ABZmonPPC uses its own screen procedure, and then,does not interfere with the operating system. The interface has menus,windows, dialogs box and uses the  mouse like a Macintosh .

Sure, the ABZmonPPC's interface is not as sophisticated as the onebuilt by Apple (the code holds in 50K bytes only), but the user willretrieve almost its familiar environment. Among other differences, one cannote that the cut and paste function is not as usual. The debuggertransfers only hexadecimal numbers ( the most used type of  keyboardentries). There are also differences in the window scroll bar. Only up anddown arrows are available, and there is no middle thump. However this lackis compensated by a fabulous scroll speed...

	
			Example of window, menu and dialog box in ABZmonPPC

Note that in the dialog box the default button is boldly outlined. Itseffect occurs if the user presses Enter or Return.
Theactive window

This window has a black close box. The first time you click on awindow (menu) it becomes active. You can move the window (active or not)as usual, the mouse being in the title window area. Click into the closebox to close the active window. In window with scroll bar, click into thearrow icon to scroll up and down. Alternatively, use the up and down key onthe keyboard. if the window has a grow box you can shrink or expand thewindow as usual.

Sometimes the active window is empty. This means that window contentcannot be drawn, probably because ABZmonPPC meets a bus/address error. Forexample the monitor probably cannot show a DUMP window at $AAAAAAAA sincethe memory for this address does not physically exist.

In the example above, the TRACE menu is active.

The default address

The default address is set when you click one time in a window andthis line become highlighted. By example, a line in a register window ishighlighted when you click in the register  name area (the value area isreserved to change the register value). The default address is the registervalue. In the dump window you must click in the dump address area (theother parts are reserved to change the memory). The default address is thehexa value at the beginning of the line. You must click in the address areaof a code window since the operand field is used to show the operand value.The default address is also the hexa value at the beginning of the line

The default address is the one shown in most dialogs asking you for anaddress. For example: to set a break point, highlight an address in anydisassemble window and click on the SIMPLE in the SET BREAK menu. Toexecute the code starting at the address in the R3 register, highlight theR3 line in some register window and click the GO TO item in the CONTROLmenu.

In the example above, the fifth line of the DISASSEMBLE window ishighlighted, so the default address is $1CA9518.

Debugger mode: PowerPC or 68K

ABZmonPPC operate has both PowerPC and 68K debugger. ABZmonPPC signalmode switch by a dialog like the one below. ABZmonPPC has entered many timeto debug PowerPC code. Then a _Debugger instruction in 68K code has calledABZmonPPC.

When a such debugger mode switch occur, a 68K code window is made thefront window. If there is no 68K code openned, a new one is created at theaddress of the PC. If the mode switch from 68K to PowerPC, a PowerPC codeis made the front window.

Sometime ABZmonPPC have to guess what the user want to do with somecommand. By example, the user may wish set a break point in some PowerPCcode while the debugger is in 68K mode. If the break point is set directlyin the PowerPC code window, ABZmonPPC assume that the break point must be aPowerPC break point. But if the command is issued from the break menu orfrom a keyboard shortcut, there is no way to know what kind of break pointthe user want install. In this case, ABZmonPPC follow this simple rule: thecommand apply to the most recently used code window. So, to be sure surethat your command apply to the right mode, make a code window the frontwindow (just click on the window). The command apply to this kind of codewindow. The are only few case ABZmonPPC have to made this guess: commandgiven in OPT DIS menu (option for disassembler), SIMPLE item inthe SET BREAK menu and / and * keyboard shortcut (to changePC displacement form and rebuild symbol/label in disassembler).

Dialog

Dialog are used to get parameter and send command to ABZmonPPC. Thedialog below is used to open a 68K code window. The default button, the onemore darker, is the OK button. This button is selected with Enter orReturn key. The check box named small font is crossed, so the window will use small font character. The edit field start hold thehexadecimal value 252B6t40. The letter t is a mistake. When the userselect un button or hit Enter or Return key, ABZmonPPC do notaccept the command and put the arrow cursor near the offending character.The arrow is empty to signal an error.

Everything written in the edit field can be copied into the ABZmonPPCclipboard by the usual Command-C. The selected string in the Clipboard window is pasted by the usual Command-V. The defaultaddress is written into the edit filed when the dialog is openned. Thedefault address come from an highlighted line in some window.

MAIN menu

This is the root menu. It open all other menus. Unlike Mac menu, menusin ABZmonPPC, can be moved and closed. If the MAIN menu is closed, you canre-open it like this: close any menu or window, then press any key or clickthe mouse anywhere. The MAIN will reappear, and you will be able to openall other menus and window.			

The items in this menu open the following menus:

CONTROL: this menu allows to return to the application, toterminate it or to continue at a given address, etc.

OPEN: this menu opens memory dump windows, code windows, messagewindows, file selector boxes, file text windows...

SEARCH:  searches a sequence of letters or hexadecimal values inmemory.

MON SPY: each time the debugger is entered, a condition a isckeck. This menus set or clear such condition (see JB Conditionsection for more on it).

STEPSPY: Like MON SPY menu, but condition is check each time atrace exception occur (initiated by some step command).

STOP: the items of this menu force a break when someconditions on the registers or/and memory occur (for example when the stackpointer increases) or when the program executes some instructions (TW, forexample).

BREAK:  sets or removes break points.

TRACE:  induces the step by step mode. Single step, "n" step, etc.

OPT DIS: each item determines the look of the code window. Forexample, the type of labels used (locals or the ones from the compiler) orthe type of microprocessor (16 or 32 bits)... Two option menus are openedsimultaneously.

MISC: to save/reload the current menus and window settings, pastean address to the CLIP buffer and set the look of the text windows.

CONTROL menu

This  menu allows to return to the current application or terminates it.

GO:  quits ABZmonPPC and continues the execution of theprogram. If the program is stopped by one of the Debug instructions, theexecution continues after the Debug instruction. If the program is stoppedby a break point, the execution continues at the instruction  under thebreak point. For other king of exception (illegal instruction, unmappedmemory) you need to continue at the next instruction: change the PCvalue in the GPR window or use the GO TO item).
Keyboard shortcut: g, q, G, Q

GO TO ...:  quits ABZmonPPC and continues the execution of theprogram at the address given in the dialog box below. The address $1416538is the default address (a line of code, at this address, has beenselected). When  no line is selected, the PC address is used instead.

GOTO NEXT:  quits ABZmonPPC and continues the execution of theprogram at the next instruction. Useful when the debugger is enteredbecause a bus error or an illegal instruction. The faulty instruction isskipped and execution resume at the next instruction.

REFRESH: quits ABZmonPPC and  rebuilds the desktop screen. Usefulto debug codes using  QuickDraw.

FINDER: quits ABZmonPPC and go to the Finder.

RTS: exit the current subroutine. See The RTScommand  below before using this command. Keyboard shortcut: r

AE QUIT: send an Apple quit event to the current application. Ifthe application support this Apple event, this can force the application tosave the current document before quit.
 
TO SHELL: quit the current application and return to the commandshell: usualy the Finder. Keyboard shortcut: e (ExitToShellprocedure...)

RESTART: restarts the computer (warm start).

The item holding only dash character is used only to separate theother items: the last one is dangerous!

Open menu

This  menu  opens all non-menu windows in ABZmonPPC.

DISASSEM: opens a PowerPC code window. You must enter the addressof the first instruction in the dialog box below. This address can be givenindirectly through registers and relative displacements (see The JBaddress). The small font check box must be checked to display thetext in the window using small fonts. as JB record check box must bechecked if you want expression in the start edit field must be keepingas JB record instead of a straight address. By example, if the expressionis PC+8, and PC value is $10000, the window open at $10008. If a stepcommand is given, the PC will probably change to $10004. Then, if as JBrecord check box is checked, the code window show now the firstinstruction at address $1000C. If as JB record check box is notchecked, the code window first instruction address still to be $10008.

If the address is not valid, the cursor changes to an empty arrow andthe text cursor appears near the first faulty character. Click the OKbutton (alternatively, hit Return or Enter key) to open the window and  theCancel button to cancel.

The combination Command-D is a shortcut to this item.

There is a more quick shortcut to open a code window: in any code,dump or register simply option-click in any line. The window open atthe address of this line.

MEM DUMP:  opens a memory dump window (in both hexadecimal valueand ascII code). A dialog box similar to the one above, asks for the startaddress.

The combination Command-M is a shortcut to this item.

There is a more quick shortcut to open a dump window: in any code,dump or register simply shift-click in any line. The window open atthe address of this line.

GPR reg: opens a window to show the value of the generalpurpose register R0 to R31. The small font check box, in the dialogbelow, must be checked to display the text in the window using small fonts.

Shortcut: Command-R

CR reg: opens a window to show the bit status of CRO to CR7

FCS reg: opens a window to show the value of the SP, TOC, CTR,LR, PC, CR, XER, RTCU, RTCL, MQ and  FPSCR register.

FPR reg: opens a window to show the value of the floating pointregister F0 to F31.

SPR reg: opens a window to show the value of the special purposeregister. Actualy, the Mac OS don’t give access to these register. This item do not open any window.

BRK PNT: opens a window showing info on all break point.

MESSAGE: opens a message window. Only one message window can beopened at the same time. If the message window is already opened, thenABZmonPPC only make it frontmost window (active).

CLIP: opens a window showing the expression in the CLIP buffer.

PROCESS: opens a window showing all applications, including thebackground one.

FILE SEL: opens a file selector window. This is the counterpart,in ABZmonPPC, of the Mac dialog you see when choosing "Open" or "Save" asin the File menu. You can hierarchically see and select file and folder.

TEXTVIEW:  sees a  text of the file selected by the previous item.

CONTEXT:  give context information as defined by Code FragmentManager.

68K DIS:  open a 68K code window. The window can be openned suchthat the first line window is address of the PC (automaticaly updated whenthe PC change), or at any given address (not updated, but with scroll bar).In the dialog below, the default address is the address got from somehighlighted line or the PC address if there is no such highlighted line. Ifthe botton AT PC is selected, the address in the start edit filedis ignored.

	

68K REG:  opens a window to show the value of the 68K register D0to D7, A0 to A7, PC, CCR and SR

SEARCH menu

To search a sequence of characters or hexadecimal values in memory.

ASCII STR: finds a sequence of letters in memory. In thedialog box below, the first edit field is an expression given the addressof the first byte of the memory segment to be scanned. The second field isthe address of the last byte in the segment. The third edit field holds thesequence of letters to be found. The symbol * is the wildcard symbol,standing for any character. So, ABZmonPPC searches every word Apple test orpart of a word like in  attention.

In this example ABZmonPPC has found the word text at the address$2164E. The dialog box below is then shown:

The DUMP button opens a memory dump at this address while the DISAS button opens a code window. The OK button exit without openningany window.

Shortcut: Command-F

HEXA STR: finds a sequence of  hexadecimal numbers inmemory. In the dialog box below, the first edit field is an expressiongiven the address of the first byte of the memory segment to be scanned.The second field is the address of the last byte in the segment. The thirdedit field holds the sequence of hexadecimal numbers to be found. Note thatthe wildcard symbol  *  can be also used in a sequence of hexadecimalnumbers.

Here the search fail in the segment [PC, PB+$2000]. The dialog belowwarn you for it:

OPTION: sets some search options. In the dialog box below, thewildcard symbol is set in the edit field wildcard symbol. The checkbox case sensitive must be checked if the search is done casesensitive. The check box use wildcard must be checked if the searchuses  the wildcard symbol as a replacement for any character.

FIND NEXT: continues the search previously initiated.

Shortcut: Command-G

MON SPY menu

Sometime you may wish to know if a byte or a word in memory haschanged since last time you have see the debugger screen. You may also wishto know if a register is becoming negative or zero. Or if a segment hasbeen corrupted. MON SPY menu let you make a command that spy fot suchthing.

CONDITION: prompt a dialog to set a condition to check each timethe debugger in enterred. Warn you when the condition is true. See JBCondition section for more on condtion syntax.

The condition in dialog ask the debugger to warn when the word at theaddress in the register R3 is greater than $FFFF. The next time thedebugger will be enterred and the condition will be true, ABZmonPPC willshow you the dialog:

ARRAY COMP: warn you if an array of byte in memory has changed.In the dialog below the first field is the address of the first byte tocheck. The second field is the number of byte to check. When the OK buttonis selected, the array image is copied into a internal buffer in ABZmonPPC.

Each time the debugger is entered, the array is in memory is compared to
the array copied in the internal buffer. If one or more byte does notmatch, the debugger warn you:

The size of the internal buffer is set in the S_UP resource ofABZmonPPC INIT (see Internals variables).

CHECKSUM: this item is very similar to the previous one. Insteadof keeping an image of the segment to check, a checksum is done. The nexttime the debugger is entered a new checsum is done. If the two checksumdoes not match, the debugger warn you. Otherwise, the debugger keep silent.

Use CHECKSUM for segment larger than internal buffer used in ARRAY COMP.

CLEAR: to cancel one or more spy process.

Note: all three MON SPY process can run concurrently.

STEPSPY menu

This menu is identical to the MON SPY menu. Dialog presented are sameas above. But, while in MON SPY check is done each time the debugger isenterred, in STEP SPY check is done every time a PowerPC instruction isexecuted.

ABZmonPPC internaly set a trace mode and check condition or segmentchange after instruction is executed. If condition is not true or no changeis done in segment, ABZmonPPC continue program execution (in trace mode) atthe next instruction. Otherwise, the debugger is enterred and a dialog warnthe user.To see how many instruction has been executed, look in the messagewindow. The number of instruction is show in hexadecimal.

Use STEP SPY with caution. If the condition never come true or if the segment is never changed, ABZmonPPC will continue to execute the program in trace mode, and this is very, very slow!

Note: all three STEP SPY process can run concurrently. In fact MON SPYand STEP SPY run  concurrently.

STOP menu

This menu forces a program to break on various conditions. Also, resetDebugNum parameters.

Use item in this menu with caution. If the condition never cometrue, ABZmonPPC will continue to execute the program in trace mode, andthis is extremely slow! When the break is done, ABZmonPPC is entered and adialog tell you why the break is done. To see how many instruction has beenexecuted, look in the message window. The number of instruction is show inhexadecimal.

					

TWO CONDITION: set condition to a break when the condition becometrue.

The first edit field in the dialog above is the  number of time thecondition become true before breaking. The two next edit field hold thecondition. If you you leave a field empty the condition is not used. TheAND button must be used to force a break when both condition are true.The OR button force a break when at least one condition is true. Usethe OK button when one or both are not used. If both condition areused the OK button is same as AND button. See JB Conditionsection for more on condition syntax.

SP CHANGE: ABZmonPPC watches the stack pointer SP at everyinstruction. If the value of SP changed, a break is forced.

SP INCREASE: ABZmonPPC watches the stack pointer SP at everyinstruction. If the value of SP increases, a break is forced. This featureis useful to get the exit from a subroutine.

SP DECREASE: ABZmonPPC watches the stack pointer SP at everyinstruction. If the value of SP decreases, a break is forced.

TOC CHANGE: ABZmonPPC watches the table of content register (R2)at every instruction. If the value of TOC changed, a break is forced.

LR CHANGE: ABZmonPPC watches the link register LR at everyinstruction. If the value of SP changed, a break is forced.

NEXT BRANCH: ABZmonPPC check every instruction until a branchinstruction (b, bc, bcctr or bclr) is to be executed. Then, a break isforced.

NEXT TRAP: if the debugger is in PowerPC mode then ABZmonPPCcheck every instruction until a trap instruction (tw or twi) is to beexecuted. When this happen, a break is forced. If the debugger is in 68Kthen ABZmonPPC check every instruction until a lineA trap instruction (OSor ToolBox call) is to be executed. When this happen, a break is forced.You set the range of the lineA trap to be intercepted in the followingdialog.

Note: the trap intercept process is cleared each time the debugger isenterred in 68K mode.

CLEAR DEBUGNUM: to reset parameters in one or all DebugNum.

See DebugNum section for more on it.

TAP PROCEDURE: a very usefull feature. It is like tapping a phoneline. When the target procedure is to be executed, the program is stoppedand the debugger is entered. In the dialog below you enter the procedurename (case sensitive) and the number of time to meet the procedure beforethe debugger was entered (0, the debugger enter the first time, 1, thedebugger is enterred only the second time, ect.).

Unlike other STOP command, TAP PROCEDURE do notslowdown  the current process at all.

When the debugger is enterred after a procedure intercept, a dialogshow for what procedure the stop is done.

There is room for up to 32 procedure interception. When the 32 arefilled, the last one is erased and replaced by the new one.

CLEAR TAP: to erase all entry in the TAP buffer.

TRACE menu

To initiate step command and set trace option

STEP: executes the instruction pointed by the PC and returns tothe debugger. (For both 68K and PowerPC mode)

Shortcut: s.

STEP AT: executes one instruction at a given address. You enterthe address in the next dialog box.  (For both 68K and PowerPC mode)

 The address can be any valid expression. Here the address is thevalue of the link register plus 8.

N STEP AT: execute N instruction at the given address.  (For both68K and PowerPC mode). The address and the number of instruction to executein trace mode are set in the following dialog:

The default address is the PC unless a line is highlighted. In thiscase the address in this line is used. The number of instruction executedis show in the message window when the debugger is re-entered.

OPTION: no yet implented

BREAK menu

To set or clear break point.

ABZmonPPC let you know when a break point is set by a message in theMESSAGE window. A message is also written when later the program isstopped by the break point:

In code window a break point is signaled by a small black boxcharacter at the start of the disassembled line. When the break point isnot valid the black box hold a white dot. Below the break point is set at$1B26D3C:

SIMPLE: set a break point that break each time. (For both 68K andPowerPC mode)

Shortcut: Command B.

An easy way to set a break point is to highlight, in a code window,the line where the break must be done, before selecting the item. Theaddress of this line appear in the edit filed as default address. Then, toset the break point, you just need hit Return kew or click the OK button.

A more quick way is to to hit the Command key while clicking aline in code window.

ONE TIME: very similar to a simple break point. But the breakpoint is automatically removed when the break is done.

To quickly set a ONE TIME break point, hit the Command key whileclicking a line in code window.

CONDITIONNAL: set a break point that break when condition become true.

The first edit field in the dialog above is the  number of time theconditionbecome true before breaking. The two next edit field hold thecondition. If you you leave a field empty the condition is not used. TheAND button must be used to force a break when both condition are true.The OR button force a break when at least one condition is true. Usethe OK button when one or both are not used. If both condition areused the OK button is same as AND button. See JB Conditionsection for more on condition syntax.

CLEAR ALL: to remove all break point. (For both 68K andPowerPC mode)

CLEAR ONE: to remove a single break point. (For both 68K andPowerPC mode)

An easy way to remove a break point is to highlight, in a code window,the break code line (the one with the black box character), beforeselecting the item. The address of this line appear in the edit filed asdefault address. Then, to remvoe the break point, you just need hit Return kew or click the OK button.

A more quick way is to to hit the Command key while clicking thebreak line in code window.

OPT DISAS menu

To set the form of disassembled line in code window (68K and PowerPC)

REDO SYMBOL: for PowerPC: with the new Code Fragment manager, aprocedure in shared library is called by name instead of by address. Byexample all Mac toolbox procedure in InterfaceLib.xcoff is called by name.ABZmonPPC keep track of all such name (symbol) at startup. A program maybuild is own set of procedure as shared library. To get the new symbol youneed to rebuild the ABZmonPPC symbol buffer. These symbol are used indisassembled line in code window. Unless you suspect an application tocreate shared library you probably don’t need to rebuild the symbolbuffer. To rebuild the symbol just click in the REDO SYMBOL item, a waituntil the dialog “Now working, please wait...” diappear.

For 68K: compiler put the name of a routine at the end the routine.The debugger keep track of these names, and show these name in the codewindow. To get the new names you need to rebuild the ABZmonPPC symbolbuffer. You need to rebuild the symbol buffer each time the application todebug is loaded. To rebuild the symbol just click in the REDO SYMBOL item.

Shortcut: * (when the PC displacement mode Symbol isselected).

REDO LABEL: (for both 68K and PowerPC mode) label in disassemblyare more readable than just plain hexadecimal address. The debugger uselocal label for all PC reference that sometime need to be rebuild. Supposeby example that you debug an application. The label you are using in thisapplication will probably not be good the next time you debug theapplication since the application will probably not be loaded at the sameaddress in memory (or some instruction are added or deleted, and PCreference no longer exactly match the label used previously). To rebuildthe labell buffer just click in the REDO LABEL item, a wait until thedialog “Now working, please wait...” diappear.

Shortcut: * (when the PC displacement mode Label isselected).

Rebuilding the address of the label takes only a fraction of seconds(unless you use a very large label buffer), so don't take any chance: usethe key '*' as soon as you suspect your code to be modified ormoved...

hexa add : set PC displacement mode as hexadecimaladdress. PC reference are given with plain hexadecimal address. (For both68K and PowerPC mode)

Shortcut: / (select the next PC displacement mode).

pc+$24 : set PC displacement mode as PC offset. PCreference are given with PC symbol ‘*’ plus an offset to PC. (Forboth 68K and PowerPC mode)

Shortcut: / (select the next PC displacement mode).

local label : set PC displacement mode as local label. PCreference are given with local label. (For both 68K and PowerPC mode)

Shortcut: / (select the next PC displacement mode).

CFM symbol : for PowerPC: set PC displacement mode as CFMsymbol. PC reference are given with shared libarary name plus offset. For68K: set PC displacement mode as compiler symbol. PC reference are givenwith compiler routine name plus offset.

Shortcut: / (select the next PC displacement mode).

MISC menu

					

SAVE MON: To save the current menu and window setups for the nexttime.

Shortcut: Command S.

LOAD MON: To restore menu and window default setups or the setuppreviouly saved.

Shortcut: Command L.

CLIP ADR: put the address of the highlighted line into the clipbuffer. If the clip buffer is full, the new address replace the last entryin the clip buffer.

Shortcut: Command S.

TRASH CLIP: erase all entries in the clip buffer. The dialogbelow make sure that you don’t make a mistake.

TEXT WRAP: a text window is viewed in two mode. In the first one,a long text line is broken (the text continues at the next row). With thesecond mode, only the part of the line that fit in the window is show (theremaining  is still invisible, but you can scroll this line horizontallywith the  left and right arrow keys). This item switches from one mode tothe other.

TEXT SCROLL: the up/down arrow icons scroll the text in a textwindow. Scrolling can be done one line at a time or more quickly, one pageat a time. This item switches from one mode to the other.
Thewindows

If the content of a window cannot be displayed, because of a addresserror  in some code window by example, ABZmonPPC leaves the window open andputs a warning in the message window. You must then close this window. Suchwindows are empty or filled with error message.

Usually, you can select a line by clicking at the start of this line.The line is then video inverted and the address involved by this linebecomes the default address (this address appears in the edit file of mostdialog boxes). To de-select the line you click another time the selectedline.

An active window is identified by its black close box. A windowbecomes active when you click inside. The keyboard key "." also makethe window active. Repeatedly hit the "." key to do a tour of allwindows.

To move a window, just put the cursor in the title bar and drag as usual.

Most of the windows can shrink or grow. Put the cursor in the size box(the two rectangle icons in the right bottom corner) and drag as usual. Thesize of the window is computed to not broke a character in the middle. Somewindows, like the register window, can shrink or grow in only oneway.

Click on the arrow icons to scroll the  text. If the scrolling is toofast use the keyboard arrows up and down.

When hit the '%' key the active window is continuoulsy refreshed.This is useful to check if some memory location is changed frequently. Thecursor changes to a short arrow. By example open a dump window at theaddress $16A and hit the '%' key. The cursor changes to a short arrowand you can see the word at $16A (the timer Ticks) change very quickly. Tostop it, press the '%' key another time.

Disassembler window

Show PowerPC mnemonic instructions.

The left column is the address of the instruction disassembled, unlessa local label or CFM symbol is used instead (here the symbol is: ResError).See OPT DISAS menu for more on it. Click on this column to select theline: the default is then the address of this line.

The next column column is the keyword instruction name. If you clickin this column you get a dialog also showing the meaning of the keyword. Inthe dialog below, the third line keyword. The meaning of this keyword isalso show in the last column of the window when first comment mode isselected.

The third column hold the instruction operand. If the mouse is hit onan operand, the operand info dialog is displayed. For integer register orimmediat value the value is show in hexadecimal, in ascII and in decimal.For displacement the value is show in hexadecimal and in decimal. Forfoating point register, the value is show as both hexadecimal and decimalfloating point. For register indirect with immediate index, the effectiveaddress is show between bracket, and the pointed value is show inhexadecimal, in ascII and in decimal.

The last column is the comment field. Two kind of comment arepresented. The first one give the meaning of the instruction keyword, as inthe code window above. The second one, as in the code window below, givethe instruction opcode between brace, the ascii value of the immediat valueoperand between double quotes, and PC displacement between < >. Hit the c key to toggle beetwen the two mode.

The fourth line begins by a black box char to indicate a break pointat this address.  When the black box has a white, the break point isinvalid. This happen when new code has erased the instruction under thebreak point (you must then clear the break point as soon as possible, seeBREAK menu). If the line begins with the character *, the addressof the line is the value of the program counter PC.

The window title reflect the address of the first line in the window.Above, the address of the first line is $409DEC20. Since the PC is$409DEC24, the first line address is PC-4 = PC+$FFFFFFC. When the textscroll (click on the arrow icons or hit on the keyboard arrows upand down), the title change according to the address of the firstline.

If the code is not word aligned in memory, hit the left or right arrow. The address of the first line decrease or increase byone.

To quickly open a dump window at the address of some line in codewindow: Shift click the line.

To quickly open a code window at the address of some line in codewindow: Option click the line.

To quickly set a simple break point (see BREAK menu) at theaddress of some line in code window: Command click the line.

To quickly set a break point that remove itself (see BREAK menu)at the address of some line in code window: Control click the line.

When you click in the address area, at the beginning of the line, youselect the line. The line is then video inverted and the address at thebeginning of the line become the default address. In the first code windowabove the fifth line is selected and the default address si $409DE30.

Dump window

Show memory content as ascII and hexadecimal number.

The left column is the address of the first byte of line. The middlearea is the hexadecimal value of each byte and the right area are the ascIIcharacter of each byte or a dot if the a such character doesn’t exist.By example, the first byte of the second line is the content of memory ataddress $8A288. The byte value is $55 and the ascII character $55 is theupper case letter U.

The tiltle reflect the address of the first line in the window. The JBaddress [r6+$20].w+$40 mean this: form an address by adding $20 to thevalue of the register r6, take the word at this address and add $40. Theresult is the address of the first line.  When the text scroll (click onthe arrow icons or hit on the keyboard arrows up and down),the title change according to the address of the first line.

To scroll horizontally, hit the left or right arrow.The address of the first line decrease or increase by one.

You can change the content of the memory (RAM only) directly fromwithin a dump window. To change the value of the memory you click insidethe line, either in the hexadecimal area or ascII area. The area is thenconverted to an edit field and you would be able to change hexadecimalvalue or ascII character. Above, the hexadecimal area in the second line
is converted to an edit field. When an error occur, because an invalidhexadecimal digit or bad number of character in edit field, the mousecursor change to an empty arrow and the text cursor goes near a faultycharacter. You must hit Return or Enter to validate the modification. Thememory is changed only after the input keyboard of one of these two keys.If you change your mind and wish do not change the memory, simply clickoutside the window.

To quickly open a dump window at the address of some line in dumpwindow: Shift click the line.

To quickly open a code window at the address of some line in dumpwindow: Option click the line.

When you click in the address area, at the beginning of the line, youselect the line. The line is then video inverted and the address at thebeginning of the line become the default address. In the window above thefourth line is selected and the default address si $8A298.

Register window

Show the GPR registers values and other user level registers values

					ict06a2009302be011a031c001102ff0c00ffffffff02be000000930000031c0000011a000000000000001e0001000a009302be011a031c0098800c009302be011a031c0000000000000000004800000048000000000001000100010000000001da3e840000000000000001800000010000ffffffffffff0000000000000000009302be011a031c009302be011a031c000002f50006007ff7ff00f806007ff7ff00f80802600020f90000180802600020f9000018080267ff20f90000180b05640123f1e1e0fc0000180b05640123033330fc0000180a046401230333fb0000180a046401230303fb0000180b05640123e301e0fc0000180b05640123030030fc0000180b05640123030030fc0000180b05640123033330fc0000180b0564012301e1e0fc000018080267ff20f90000180802600020f90000180802600020f900001806007ff7ff00f8060060f7000018060060f70000180d01639efe000638278e39f78e180d016451fe0006446451450451180d016411fe0006442451050450180d01639efe000644245f09e790180d016050fe0006442451110450180d016450fe0006442451210451180d016390fe00063827917d078e18060060f7000018090060fa00037fffe018060060f70000180d0b67ce38000038278e09e38e180d0b6111440000446451191451180d0b6111400000442441291050180d0b6111400000442442491090180d0b61114000004424447d1110180d0b6111440000442448091211180d0b610e38000038279f09e7ce18060060f7000018090060fa000301ffe018060060f70000180d0b639f78000038e38e7df082180d0b6444440000451451050186180d0b640444000045145105028a180d0b640478000045144e09e492180d0b64044400004514511107df180d0b6444440000451451110082180d0b638444000038e38e11f08218060060f7000018060060f7000018060067f7ff00980d0163e1feff06c71c71831c7d980d0163eefeff06baebaebeebb9980d0163eefeff06baebae86ebb5980d0163e1feff06baebb1fb1bad980d0163eefeff06baebaefaec20980d0163eefeff06baebaebaefbd980d01602efeff06c71c71c71c7d9b060067f7ff0098060067f7ff0098060060f70000180d01678efe00063827827ce38e180d016451fe0006446446411451180d016450fe0006442442401051180d016790fe0006442442786191180d016410fe0006442442401051180d016411fe0006442442411451180d01640efe000638278240e38e18060060f7000018090060fa000301ffe018060060f700001b0d01639efe000638e38e38e382180d016451fe0006451451451446180d016411fe000604145145144a180d01641efe0006082451451452180d016411fe000610445145145f180d016451fe0006208451451442180d016391fe00067df38e38e38218060060f7000018060060f7000018060060f70000180d0b645f78000038e38e38e39e180d0b6290440000451451451451180d0b61104400004514514514511b0d0b611e78000045145145145e180d0b6110440000451451451451180d0b6290440000451451451451180d0b645f44000038e38e38e39e18060060f7000018080060f9000207e018060060f70000180d0b679f39100038e38e39e7c2180d0b6444451000451451451406180d0b644441100045145145140a180d0b6784411000451451451792180d0b644441100045145145141f180d0b6444451000451451451402180d0b644438e00038e38e39e40218060060f7000018080060f9000207ff98060060f70000180d0b679f39000038e38e79f38e180d0b6444450000450451441451180d0b644441000045e451441451180d0b6784410000451451442391180d0b64444100004513cf444451180d0b6444450000451041444451180d0b644439f00038e38e78438e18060060f70000180c0060fd00007ffeff02f80018060060f70000180d01644efe000638e38e38e38e180d0166d1fe0006451451451451180d016551fe0006451451451451180d016451fe0006451451451391180d016451fe00064514514514511a0d016451fe0006451451451451180d01644efe000638e38e38e38e1807016001f8000018060060f7000018060060f70000180d0b67de38e78038e38e38e38e1a0d0b6411451440451451451451180d0b6411410440451451451451190d0b679e390780451451451451180d0b64100504404514514514511a0d0b6410451440451451451451180d0b641038e44038e38e38e38e18060060f700001b060060f7000018060060f7000018060060f700001806007ff7ff00fa06007ff7ff00fb02f5000000ff

The first column hold the registers names, the second hold theregisters values in hexadecimal. To point out the  change in register,ABZmonPPC saves a copy of all registers. When the debugger is entered, acomparison is made between the old and new register values and thedifference is underlined in the window. For example, the last two digit ofthe RTCU register in the FCS window above are changed since last timethe debugger was enterred.

To select a line, click into the register name. The register valuebecome the default address. In the FCS window above, the LR line isselected. The default address is then the value of the Link Register:$85894.

To change a register value, click into the the register hexadecimalvalue. The hexadecimal area is then converted to an edit field and you canchange the register value. In the GPR window above the R20 registerhexadecimal value is then converted to an edit field. When an error occur,because an invalid hexadecimal digit, the mouse cursor change to an emptyarrow and the text cursor goes near a faulty character. You must hit Returnor Enter to validate the modification. The register value is changed onlyafter the input keyboard of one of these two keys. If you change your mindand wish do not change the register, simply click outside the window.

To quickly open a dump window for a register in window: Shiftclick the line of this register.

To quickly open a code window for a register in window: Optionclick the line of this register.

Condition register window

Show the Condition Register bits status of CRO to CR7.

When the letter is upper case the bit is set, else the bit is clear.Above the G bit of CR0 is set and the other bit are clear. The meaning ofthe letter are:

for CR1:

	S: Floating-point exception (FX)
	E: Floating-point enable exception (FEX)
	V: Floating-point invalid exception (VX)
	O: Floating-point overflow exception (OX)

other:

	L: Less than [negative] (LT)
	G: Greatest than [positive] (GT)
	E: Equal [zero] (EQ)
	O: Summary overflow (SO)

To point out the  change in CRn, ABZmonPPC saves a copy of CR. Whenthe debugger is entered, a comparison is made between the old and new CRvalue and the difference is underlined in the window. For example, the G and e bit in the CR window above are changed since last timethe debugger was enterred.

Floating-point register window

Show the value of floating point register as hexadecimal number anddecimal floating-point (scientific notation).

The first column hold the register name, the second hold the registervalue in hexadecimal and the third the decimal floating-point form of theregister value. To point out the  change in register, ABZmonPPC saves acopy of all floating-point registers. When the debugger is entered, acomparison is made between the old and new floating-point register valuesand the difference is underlined in the window. For example, the first andfourth digit of the FP6 register in the FPR window above are changedsince last time the debugger was enterred.

To change a floating-point register value, click in the hexadecimalarea. A dialog appear (below) with the register hexadecimal value of theclicked line. When the change is done, click on the OK button tochange the register value. When an error occur, because an invalidhexadecimal digit, the mouse cursor change to an empty arrow and the textcursor goes near a faulty character.

If the mouse button is hit while the cursor is on thefloating-point register name or in the decimal floating-point area, adialog similar to the previous one, but with decimal number instead ofhexadecimal number, is show. Use the OK button to change the registerwhen the modification is done. When an error occur, because an invalidcharacter, the mouse cursor change to an empty arrow and the text cursorgoes near a faulty character.

Here the value of the FP5 register is partially shown. The exponent(+38) is not visible because the dialog is not large enough. When thishappen use the left or right arrow key to scrollhorizontaly the text and uncover the invisble part.

Break point window

Show the when and how the break point are set.

The first column in window is the break point number. The second isthe address in memory where thebreak point is set. The third column hold asingle character: A when the break point automatically remove byitself, I when the break point is invalid, and a blank spaceotherwise. The fifth column is the number of time the program must meet thebreak point before really stopping. Each time the program cross the breakpoint, the number in the fourth column is decremented by one. When thecount is 0, the program is stopped and the debugger is entered. The lastcolumn show which and how conditions are used. In the window above thebreak point no. 0 is an invalid simple break point. The break point no. 1is a valid simple break point that remove itself. The break point no. 2 usetwo condition and the count is decremented when both condition are true.The count must be decremented only one time before stopping. So, the stopis done the first time the two condtions become true.

When a break point is not used the line is empty. See BREAK menu for more on condition and how to set break point.

To select a line, click into the break point number. The break pointaddress become the default address. In the BREAK POINT window above,the break point no. 1 line is selected. The default address is then$1DA39E0.

To modify a break point click in the line of the break point after thecolumn of break point number. To create a new break point, click in anempty line. A first dialog is used to set the break point address.

If the OK button is selected, a second dialog is used to modifyor set the other parameter.

To set a simple break, by example, set the address in the first dialogand in the second dialog, set X to 1 and leave other field blank.

Message window

Display the ABZmonPPC warning/error/info messages.

The messages are numbered from 1, in hexadecimal. The first message inwindow is always the most recent and then, has the highest no. The windowcan grow to uncover the older messages. There is no arrow icon in window,so you cannot scroll the message. When the maximum size of window isreached, the older messages are lost (the message are stored in a cyclebuffer that hold a maximum of 20 messages).

Only one message window can be opened at the same time. If themessage window is already opened, then ABZmonPPC only make it frontmostwindow (active). If the message window is close and there is an incommingmessage, the debugger re-open the window, make it front and display the newmessage.

Clipboard window

Show the strings in the ABZmonPPC clipboard buffer.

When a line is highlighted in some, the command CLIP ADR of theMISC menu (or the keystroke Command C) store the default addressof this line into the ABZmonPPC clipboard. The button CLIP in the Calculator dialog store the edit string into the CLIP buffer. Every stringin any edit field is stored into the clipboard by the keystroke CommandC.

When a string is highlighted in the clipboard window, the keystrokeCommand V replace the edited string by the highlighted string .Adialog is open with either the highlighted string in the clipboard windowor the default address.

When the clipboard buffer is full (40 entries), the new string replacethe last stored string. The TRASH CLIP item the MISC menu erase all entriesin the CLIP buffer.

Process window

Show the current active process (application).

The first line in window hold the column title. The first column, Name, is the name of the application. The second column, PSN, is theprocess serial number. The third, Type, is the application type. Thefourth, Sign, is the creator signature. The column Mode  givessome information from the application "SIZE" resource. The starting addressof the application code holds in Location column while the Sizecolumn gives the application size. FreeMem shows the amount of memoryavailable for the application and Laucher PSN, the number of theparent application (generally the Finder). The current running application(here applPPC) is marked by a carret symbol just before the applicationname.

To leave the current application, and swich to an other application,click one time in the application line. Below, the fifth was selected, sothe application ResEdit will be activate.

File selector window

These windows  select a file (this is like the standard file selectorbox, in the Mac, you can see when you open a document).

    

The first time you open a file selector window you see the list of allconnected disks, including the one shared. Look at the first window above.The caret symbol tells the line is a disk name or a folder name. If youclick on the disk DEV_disk name, the window show the root level of thisdisk. A folder in this disk is named MPW. A mouse click on the MPW nameshow the content of this folder, as in the middle window. This windowdisplays, after the dashed line, the content of the second hierarchicalfile level of the disk DEV_disk. Scrolling up the window content let yousee other file and folder at this level, like in the third window. A textdocument is identified by the the letter t, before the file name. Toselect a document, click anywhere in the document line.

Briefly, the lines before the dashed lines give the folders' hierarchywhile the lines after the dashed lines give the content of the last folderin the hierarchy. You click on the lines after the dashed lines toselect a document or to open the folder (this folder moves before thedashed line and becomes the last folder in the hierarchy). You click on aline before the dashed lines, in the folders' hierarchy, to open(after the dashed line) the folder or the disk of this line. For example,to return to the root level, as in the first window, click on the firstline of the second window, named Disk.

When a document line is selected, like MPW.Help in the third window,you can read this document. Go on the OPEN menu and select TEXTVIEW.

Text viewer window

Show the content of the selected document in a FILE SELECTOR window.

In the window above you cannot see the fifth line entirely becouse thewindow is not large enough. Go to the MISC menu and select the TEXT WRAPitem. The text look now like the window above.

You can also scroll horizontally the first line of the window with theleft and right arrow keys.

Note: all documents can be viewed, not only text window. But non-texthold many garbage characters show as empty rectangle, and so aremeaningless outside text section.

Context window

Give context information as defined by Code Fragment Manager.

The first line is the content ID of the code to be executed. Thesecond line show the connection ID and connection name. The third line givethe section number and where this section is located in memory. The lastline is the name of the procedure and the address of start of the procedurecode.

68K DIS window

Show 68K mnemonic instructions.

The left column is the address of the instruction disassembled, unlessa local label or compiler symbol is used instead (here the lavel are c_3and c_4). See OPT DISAS menu for more on it. Click on this column toselect the line: the default is then the address of this line.

The next column column is the keyword instruction name. The thirdcolumn hold the instruction operand. If the mouse is hit on an operand, theoperand info dialog is displayed. By example, the dialog below is promptedwhen the mouse hit the operand in the line pea -4(a5). $236539C is thevalue of a5 minus 4 and $A5328 is the value at the address $236539C

The last column is the comment field. The second one, as in the codewindow below, give the instruction opcode between brace, the ascii value ofthe immediat value operand between double quotes, and PC displacementbetween < >.

The third line begins by a black box char to indicate a break point atthis address.  When the black box has a white, the break point is invalid.This happen when new code has erased the instruction under the break point(you must then clear the break point as soon as possible, see BREAKmenu). If the line begins with the character *, the address of theline is the value of the program counter PC.

If the window is openned at PC (see 68K DIS in the Openmenu) the first line of the window is always the instruction code at thePC address. This line is updated each time the PC value change. There isnot scroll bar for this window. The other kind of 68K code window is notupdated when the PC change, but have a scroll bar. If the code is not wordaligned in memory, hit the left or right arrow. The addressof the first line decrease or increase by one.

To quickly open a dump window at the address of some line in codewindow: Shift click the line.

To quickly open a code window at the address of some line in codewindow: Option click the line.

To quickly set a simple break point (see BREAK menu) at theaddress of some line in code window: Command click the line.

When you click in the address area, at the beginning of the line, youselect the line. The line is then video inverted and the address at thebeginning of the line become the default address.

68K REG window

Show the value of the 68K register D0 to D7, A0 to A7, PC, CCR and SR

The last two row show the bit value of the SR. The cc' row show thelow byte of the SR (the CCR). The SR row show the high byte of SR. When thebit is set, the corresponding letter is upper case. When the bit is clear,the letter is lower case.

The calculator

The calculator is a dialog box that makes calculations and conversionsin  hexadecimal, decimal, octal, binary numbers and in ascII characters. Tocall the calculator, simply hit the key "=".

In the Expression edit field you enter the expression to compute. Thecalculation is done when you hit the Return or Enter key or theCOMPUTE button. When an input error occurs, the cursor changes to anempty arrow and goes near an offending character. The CLIP IT buttonadds the computed value into the CLIP buffer. The computed value is alsokept in memory, and used as a default value for the calculator when thereis no line selected in a window. Use the CANCEL button to close thecalculator.

The calculator shows the five conversions in the dialog box using aleading symbol to point out the kind of number. The ascII conversion,between double quotes, uses empty rectangle for unprintable character.

As an input, the calculator accepts hexadecimal numbers (with leading$), decimal numbers (without leading #), octal numbers (with leading @) andbinary numbers (with leading %). A number without leading is assumed inbase 16. This default value can be changed in the S_UP variable Default base number. The calculator also accepts  numbers in ascII forms,like "abCd" or 'zx' between single or double quotes, of one to fourletters. Each letter counts for a byte in a long integer (four bytes). Inthe last two examples the long integer values are $61624364 and $00007A78.

The calculator uses the following operator, given in ascendingpriority order, as defined by the C language:

-  ~		minus unitary and biwise not
/ *		division and multiplication
+ -		addition et substraction
<< >>	left and right logical bitwise shift
&		bitwise 'and'
^		bitwise 'xor'
|		bitwise 'or'
()		parenthesis

When the calculator is opened, the default value is the last valueused by the calculator, unless a line is selected in any window. In thiscase the default address for this line becomes the default value for thecalculator. To make a conversion of a register, for example, just selectthe register and press the key  '='.

The JB addresses

JB addresses are addresses given with  register indirections anddisplacements. There are many forms accepted by the debugger. The generalform is:

			[Rn+disp1].s+disp2

where Rn is a PowerPC register (R0-R31, SP, PC, LR, CR, TOC, CTR,XER, MSR), disp1 and disp2, the displacements and .s thesize of the element in memory (.b -> byte, .h -> half word, .w -> word).If .s is not used, the size word is used by default. Rn, disp1and disp2 are optional.

Here are some examples of JB addresses:

			[PC+5000E]+20

if PC = 20000 and the value of the word integer at the address 7000E(it was 20000+5000E) is 44444, then the JB address is 44464 (it was44444+20)

			[22222].b-20

if the byte at the address 22222 is 84 then the JB address is 64 (itwas 84-20)

			[R6]

if R6 = 44444 and if the word integer at this address is 12345 thenthe JB address is 12345

			SP+20

if the stack pointer holds 66666 then the JB address is 66686 (it was66666+20)

			R4

the JB address is the address of the R4 register

			E3678

the JB address is E3678

The JB conditions

JB conditions are  expressions holding two JB addresses. Thecomparisons are done on non-signed integers only. The general form is:

			JB1 op JB2

where JB1 and JB2 are JB addresses and op one of theoperators:

<	>	strictly smaller, greater
<=	=<	smaller or equal
>=	=>	greater or equal
=		equal
<>	><	not equal

Here are some examples:

			R5>6

To respect this condition, the R5 register value must be strictlygreater than 6.

			[22222].w=[22224].w

To respect this condition, the word (4 bytes) at the address 22222must be the same as the one at the address 22224.

			[PC].w<=C0000000

To respect this condition, the current instruction must be a TWIinstruction (Trap Word Immediate).
The RTS command

The RTS stand for ReTurn from Subroutine. RTS is an opcode for MC68000microprocessor. In 68000 assembly a subroutine is called by BSR and JSRinstructions. The subroutine terminate by an RTS instruction. The RTSinstruction tell the microprocessor to resume at the instruction after theBSR or JSR.

In PowerPC assembly a subroutine is called by branch instructions BL,BCL, BCCTRL or BCLRL. The L at the the end of these opcodes tell themicroprocessor to save the return address, that is the address after of theinstruction after the branch instruction, into the link register LR. At theend of the subroutine, the value store in LR is used to resume at theinstruction after the branch instruction. The RTS command do exactly thesame thing. When you give a RTS command, the debugger execute theremainning of the current subroutine and stop just after the branchinstruction that called the subroutine.

A program is a routine that call a subroutine that itself call aninner subroutine, etc. When the debugger is enterred, the PC is probablyvery deep in the hierarchy of subroutines. To return to an higher level youcannot just send many RTS command. The first RTS command work correctly.The debugger stop after the caller instruction. But the second RTS commandre-execute the same subroutine, and this is surely not what you wish. Tounderstand what is happenning (and what to do to execute the higher levelsubroutine) we must remember how a subroutine is called in PowerPCassembly. The PowerPC architecture define a standard way to call aprocedure. The code below show how a program call the a subroutine
named SUBROUTINE_A.

			bl	SUBROUTINE_A		# save address of nop								instructiom into LR and								 								branchto SUBROUTINE_A

			nop					# instruction that do								nothing

			...					# many other instructions

SUBROUTINE_A:	...					# instructions for the								subroutine
			blr					# branch to nop instruction

The last instruction of the subroutine, BLR, the microprocessor tobranch at the instruction pointed by the value of LR. The value of LR isthe address of the NOP, saved at the BL instruction. Now what to do, ifinside SUBROUTINE_A, we need to call an other subroutine? We cannot simplyuse an other BL instruction, since the current of LR, the return address ofSUBROUTINE_A, will be loose. The mechanism defined in PowerPC architectureto call many subroutine hold in two very small piece of code
called prolog and epilog.

At the beginning of the procedure, the prolog save the value of the LRin stack. At the end of procedure the epilog restore the LR value. Thereturn address is never loose. The code below show what happen when thesubroutine SUBROUTINE_A call itself an other subroutine SUBROUTINE_B.

			bl	SUBROUTINE_A		# save address of nop								instructiom into LR and								 								branchto SUBROUTINE_A

			nop					# instruction that do								nothing

			...					# many other instructions

SUBROUTINE_A:	mflr	r0
			stwu	r0,-4(sp)			# save LR
			stwu	sp,-56(sp)			# stack space needed								for  cross-TOC call
			bl	.SUBROUTINE_B
			nop	

			lwz	r0,56(sp)
			mtlr	r0				# restore LR
			addi	sp,sp,4+56			# clean stack

			...					# instructions for the								subroutine
			blr					# branch to second nop

SUBROUTINE_B:	...					# instructions for the								subroutine
			blr					# branch to first nop

As you see, before to call SUBROUTINE_B, the subroutine SUBROUTINE_Asave the LR in the stack (with other value like the TOC register forcross-TOC call). After the execution of SUBROUTINE_B, the saved LR isrestored and SUBROUTINE_A can return correctly.

Suppose now that inside SUBROUTINE_B you send a RTS command. Thedebugger execute the ramainning of the subroutine and resume at the secondNOP (inside SUBROUTINE_A). For a short peroid of time, namely, before the 3instruction after the BL .SUBROUTINE_B instruction (NOP, LWZ  and MTLR),the LR is a scrap register. You cannot send an other RTS command. But afterthe MTLR instruction, the LR hold the return address of SUBROUTINE_A, it issafe to send the second RTS command.

What you have to do to exit SUBROUTINE_A when you are SUBROUTINE_B issend a first RTS command, then trace the 3 instructions for which the LR isnot a valid return address. As soon as the LR change, it is safe to send another RTS command. And you can repeat to jump to return to the procedurethat call SUBROUTINE_A itself. Trace the 3 next instructions (until the LRchange value) then send an other RTS command.

For some procedure, it may have more than 3 instructions to trace.Also some compiler may use different epilog code. So you can have to trace4 or r instructions until the LR was loaded with a new (valid return)address. But as soon as the LR change, it is safe to send the RTS command.

To send an RTS command, use the RTS item in the Controlmenu. Or just it the r key on the keyboard.
The peril ofTrace in MixedMode

The MixedMode manager is invoked when a procedure in 68K is to beexecuted by the PowerPC processor. Two Mac OS procedure are called totranslate the 68K code into PowerPC code: CallUniversalProc and CallOSTrapUniversalProc. These two procedures soon call the twiinstruction to emulate 68K code. The MacOS exception handler seem havetrouble to trace correctly the twi instruction or at least, tracing inMixedMode. A way to circonvent the problem is to never let the user enterin the MixedMode code (the MacsBug way!). ABZmonPPC let you enter inMixedMode, but warn you before. When youare tracing CallUniversalProcand CallOSTrapUniversalProc, the debugger show you the followingdialog.

The EXEC SUB execute the subroutine (sending a RTS commandto the debugger) and resume into ABZmonPPC at the end of the procedure.
With the STEP you continue to stepping as usual. Be warn thatsome procedure into the MixedMode enter then in infinite loop and neverexit. The Next time skip this dialog check box must be turned on ifyou wish not to see this dialog again. In this case the count in N STEPAT (in the TRACE menu), TWO CONDITION in (STOP menu), or inConditionnal Break point are not updated. If the check box is off and thedebugger is in trace mode (when the ABZmonPPC is not shown), the currentprogram is stopped and the debugger is entered:

	

Any further trace command will then redisplay the WARNING dialogabove.

DebugNum

This procedure works like Debugger or DebugStr, but insteadof stopping the program and call the debugger just after this instruction,DebugNum stops the program only after a number of time. DebugNumneeds three parameters. The first, called 'count', is a word integer.If count=0, the stop occurs the first DebugNum is meet. If count=1, the first time DebugNum is meet, nothing happen. The stop occursonly the next time. Each time the PC is at a DebugNum instruction, thecount parameter is decrement by one. When count is 0, thedebugger is called. The second parameter, called 'Number', is a word,between 0 and 31, identifying the DebugNum call. You can then use upto 32 different DebugNums. The third parameter, 'pString' is apointer to a Pascal style string. This string is prompted by debugger whencount is 0.

The assembly code to call this procedure is

###########

	li		r3,7				# count
	stwu		r3,-4(sp)
	li		r3,6				# DebugNum no. -> 'Number'
	stwu		r3,-4(sp)
	lwz		r3,test_str[TC](rtoc)	# the string to show -> 'pString'
	stwu		r3,-4(sp)
	_DebugNum

###########

	tc		test_str[TC],test_str_[RO]
	csect		test_str_[RO]

	string	Pstring

	dc.b		'A Pascal style string example'

	align	3

###########

Re-initialisation of DebugNum

ABZmonPPC holds in memory 32 word integers, associated to the 32  DebugNums. These 32 integers hold the number of time the DebugNumsare meet.When a word integer match the 'count' parameter (previouly wehave say that 'count' is 0) ABZmonPPC stops the program, else the wordinteger is increased by 1.

Suppose that your program ends before the word integer match the 'count' parameter. The next time you will use DebugNum (for the same'number', after having rebuilt your program, by example) ABZmonPPCwill continue to use the previous value of the 32 word integers. If youtest a new version of your program you may wish use a fresh copy of one orall of these 32 word integers. In this case go to the STOP menu and clickinto the CLEAR DEBUGNUM item. The dialog prompted allow you to reset one arall DebugNums.
ABZmonPPC special keys

command 'd' key -> open disassemble window
command 'm' key -> open memory dump window
command 'r' key -> open GPR register winfow
command 'b' key -> set a simple break point
command 's' key -> save current window setup and ABZmonPPCvariable
command 'l' key -> reload  current window setup and ABZmonPPCvariable
command 'f' key -> search ascII partern
command 'g' key -> search next occurrence
command '- ' key -> open stat window
command '6' key -> open 68K register window
command 'c' key -> copy highlighted address to (ABZmonPPC)clipboard
command '0' key (zero) -> Enter to the other debugger (MacsBug ?)
option ESC key -> re-initialise mouse

'up arrow' key -> scroll down
'down arrow' key -> scroll up
'left arrow' key -> scroll left
'right arrow' key -> scroll right
ESC key -> show user screen

The following key are are upper/lower case unsensitive

'g' key -> return to user program (go)
'q' key -> return to user program (quit)
's' key -> step one instruction
'e' key -> ExitToShell (cancel current process)
'=' key -> calculator dialog
'*' key -> reset the lable/symbol
'/' key -> change disassembled displacement form: hexa address,*+$24, local label, CFM symbol
'c' key -> toggle comment form in disassemble window
'?' key -> help window
'.' key -> use repeatedly to do a tour of all windows
'%' key -> for the current window to redraw continiously
'r' key -> do a PowerPC RTS

To simulate the mouse moves and clicks use theses keys

option 'left arrow' simulate mouse left move
option 'right arrow' simulate mouse right move
option 'up arrow' simulate mouse up move
option 'down arrow' simulate mouse down move
command-option 'left arrow' mouse left move and button down
command-option 'right arrow' mouse right move and button down
command-option 'up arrow' mouse up move and button down
command-option 'down arrow' mouse down move and button down
command-shift '3' key -> take screen snapshot

Special key used in edit field only (dialog and dump/register window)

'Tab' key -> go to next edit field
'Return' key -> simulate default button
'Enter' key -> simulate default button
'Esc' key ed_exit -> simulate default button
'left arrow' key -> move left one char the text cursor
'right arrow' key ->  move right one char the text cursor
'backspace key' -> backward delete
'delete' key -> forward delete
command 'c' key -> copy to (ABZmonPPC) clipboard
command 'v' key -> paste to (ABZmonPPC) clipboard

Internal variables (PowerPC)

These variables are used to change some ABZmonPPC features like thevideo monitor where the debugger appears, the ABZmonPPC screen size, thelook of the code window, the size of the font used in the menus, etc. Somevariables must be manipulated with caution, like the one in the exceptiontable.

You change these variables with ResEdit. Open the  S_UP number 1. Thewindow show the name of the variables and their default values:

Here is the list of the variables and their meanings:

The first 16 are the exception handle by the Mac OS. When a bit is set(the value 1 is selected) the exception is signaled by the debugger.Otherwise the ABZmonPPC ignore the exception and let Mac OS deal with it(generate a System error message).

Unknown: This exception code is defined for completeness only

Illegal: The processor attempted to decode an instruction that iseither illegal or unimplemented (ABZmonPPC use it, leave it to 1)

Trap: The processor decoded a trap type instruction that is notused by the system software (ABZmonPPC use it, leave it to 1)

Access: A memory reference resulted in a page fault because thephysical address is not accessible

Unmapped: A memory reference was made to an address that is unmapped

Excluded: A memory reference was made to an excluded address'

Read-only: A memory reference was made to an address that cannotbe written to

Page: A memory reference resulted in a page fault that could notbe resolved

Privilege: The processor decoded a privileged instruction but wasnot executing in the privileged mode

Trace: This exception is used by debuggers to support single-stepoperations (ABZmonPPC use it, leave it to 1)

Brk. instr: This exception is used by debuggers to supportbreakpoint operations

Brk. data: This exception is used by debuggers to supportbreakpoint operations

Integer: This exception is not used by PowerPC processors

Floating: The floating-point processor has exceptions enabled andan exception has occurred'

Stack overf: The stack limits have been exceeded and the stackcannot be expanded

Termination: The task is being terminated

Stack: the internal ABZmonPPC stack size. Not already implented.Leave it to 0

Max step: the maxmum number of step to do in trace mode before thedebugger appear. A value 0 mean that ABZmonPPC never stop the trace untilthe number of step specified by n-step command is reached or thecondstions come true in conditional step command. Since trace mode isvery slow, this is a good protection againt waiting for nothing

Key Delay:  delay to repeat the key when the key is still down.

Mouse Delay: delay to accept a second click of the mouse.

Display width: the width of the ABZmonPPC screen. Never let thisvalue smaller than 432. Some dialog boxes have this width.

Display height: the height of the ABZmonPPC screen. Never let thisvalue smaller than 240. Some dialog boxes have this height.

Display X: the X coordinate of the left upper of ABZmonPPC screen.A value of 32 puts the left upper of ABZmonPPC screen at 32 pixels of theleft side of the video monitor.

Display Y: the Y coordinate of the left upper of ABZmonPPC screen.A value of 40 puts the left upper of ABZmonPPC screen at 40 pixels of theupper side of the video monitor.

Maximum number of window: the maximum number of windows that canbe opened at the same time in the debugger.

Use big font in Menu window: if 0, the text in menus appear withsmall font and if -1, a bigger font is used instead.

Use big font in Message window: if 0,the text in message windowappear with small font and if -1, a bigger font is used instead.

Don't report OS event: a source of trouble occurs if the OS updatewindow or cursor when the ABZmonPPC screen is displayed. One way tocircumvent is to clear the low memory variable SysEvtMask ($144). No eventis then reported. When the bit is 0, the debugger clears SysEvtMask whenABZmonPPC screen is displayed and restores SysEvtMask when it returns. Ifthe bit is 1, the debugger doesn't change the low memory variable. Usedonly when 'Low level input' bit is set.

Mouse re-center: the Mac OS don't report the mouse move outsidethe rectangle screen. When the bit is set to 1, the debugger reset themouse to the center when the mouse is near the rectangle border. TheABZmonPPC cursor can then move in any direction.  Used only when 'Low levelinput' bit is set.

Mouse not coupled: when the low memory variable CrsrCouple ($8CF)is set the cursor moves according to the mouse movement. Since ABZmonPPCuses its own cursor, there is no need for the mouse to be coupled with theMac cursor. If the bit is 1 the debugger clears CrsrCouple when ABZmonPPCscreen is displayed and sets CrsrCouple when it returns. In this way theMac cursor is not moved. You can clear the bit if the Hide/Show cursor bitis 1.  Used only when 'Low level input' bit is set.

Hide/Show cursor: the QuickDraw cursor is handle at the interrupttime. Sometimes, it happens that the cursor is changing when ABZmonPPCtakes control of the screen. Back to the program, there will be a mix-up ofthe old and the new cursor image. The result is garbage on the screen wherecursor sits. If the bit is 1, ABZmonPPC corrects it automatically. If youwork on routine modifying the cursor, let this bit to 0. ABZmonPPC will notinterfere.

Use wildcard in Search: the searches (issued of the SEARCH menu)are done using the wildcard symbol if this variable is -1; if the variableis 0, ABZmonPPC does not use wildcards.

Wildcard symbol in Search: the wildcard symbol used for thesearch. The usual symbols are '*' and '?'

Case sensitive in Search: the searches are done by distinguishingupper and lower case letters when this variable is -1. If the variable is0, ABZmonPPC does not make the difference between upper and lower caseletters.

The following variables determine the look of the code windows.

Tab length: the fields in a line of code are separated by  tabs oflength given by this variable.

Disp. form: sets the form (by default) of the operand displacement:
0 -> $1234,(pc)
1 -> *+32
2 -> local_label+22
3 -> CFM_symbol+22.

Hex prefix is Ox: if 0 the hexadecimal number has a leading symbol$, else the C style prefix 0x is used

Default number is decimal: if 0 the default base number indisasembly is hexadecimal, else the base number 10 is used.

Add first comment: if non-zero the the hexadecimal code of theinstruction, the branch address and the immediat value of the instructionare added at the the end the disassembled line.

Add second comment: if non-zero the the meaning of the instructionmnemonic is added at the the end the disassembled line.

Use simplified: code instruction are translated to simplifiedmnemonic when this variable is non-zero. Otherwise standard mnemonic areused

Add instruction adr: when non-zero the instruction address inmemory is show at the start of the disassembled line.

Add instruction code: when non-zero the instruction code is showin the first comment (see above).

Two blank before label: two blank carracter are added before thelabel name, when this variable is non-zero. This help to locate the lablein the code window.

Only 601: when non-zero, only PowerPC 601 instruction isdisassembled, not the 620 instruction.

PC (disp) symbol: this symbol replace the address of theinstruction for branch target address.

Comment 1 symbol: to mark the beginning of the first comment

Comment 2 symbol: to mark the beginning of the second comment

Register name set: 1 -> lower case name, 2-> uppercase name, 3->upper case with SP and RTOC standing for r1 and r2

Local label buffer size: the size of buffer to store the locallabel and their addresses.

NB instr. between 2 label: estimated number of instruction betweentwo label.

Percentage after central instruction: label are taken before andafter the central instruction. the value 50 in this variable mean there areas much label before and after central instruction.

CFM symbols buffer size: the size of buffer to store the CFMsymbols info.

Mon comparison segment length: the maximum length of the segmentused in ARRAY COMP of MON SPY menu.

Step comparison segment length: the maximum length of the segmentused in ARRAY COMP of STEP SPY menu.

Default number base: the number base used in edit field, fornumber shown without leading (base) symbol ($, #, @, %)

The next 6 variables set the debugger screen color. The foregroundvalue 30000, -1, -1 and the background value 0, 0, 0 show the ABZmon imagein blue with black character.

Foreground Red: the debugger screen foreground red depth.

Foreground Green: the debugger screen foreground green depth.

Foreground Blue: the debugger screen foreground blue depth.

Background Red: the debugger screen background red depth.

Background Green: the debugger screen background green depth.

Background Blue: the debugger screen background blue depth.

Turn to BW to display image: when non-zero, ABZmonPPC switch thescreen resolution to 1 bit mode, and then display the debugger image. Thismethod completly bypass the Quickdraw. With zero value, ABZmonPPC useCopyBits procedure to show the color debugger image.

Save screen image: The screen image under the ABZmonPPC screen issaved if this variable is set to -1. If you use only one video monitor youmust use this variable value. If you use a second monitor, it is notnecessary to keep this image, you save a bit of memory and more, you seethe ABZmonPPC screen even after the debugger has quit.

Screen monitor no: if you have more than one video monitorsconnected to your computer, you can choose the monitor for the ABZmonPPCscreen. If you set the value of this variable to 0, the ABZmonPPC screenappears on the main video monitor . The first, second, third... videomonitors are selected for the value 1, 2, 3...

RowBytes adjustment: internal use. Leave it to 0

Get BW pixel map from slot: the pixel map is copied directly fromthe video slot when this bit is set. Otherwise the pixel map is get fromthe
GDevice for the selected video monitor. Keep it to 0 unless you getsome problem with not standard video monitor.

Text scroll one page: in a text window, the scrolling is done onepage at a time (window size), if the variable is -1 and one line at a time,if the variable is 0.

Text window wrap: in a text window, a line too long to fit inthe window is broken and continues on the next row when this variable isset to -1. If the variable is 0, the remaining of the line is not shown.

Internal variables (68K)

These variables are used to set the 68K exceptions that ABZmonPPC mustuse as 68K debugger. If the exception is set to 1, the exception is handleby ABAmonPPC, otherwise the exception is handle by the system or by another debugger loaded before ABZmonPPC (like MacBug)

You change these variables with ResEdit. Open the  r68K number 1. Thewindow show the name of the variables and their default values:

The exception listed in this resource are the most frequently involvedby programming error. You can set all of them when the virtual memory isnot not active. When the virtual memory is used, you must clear 'Bus error'exception, since this vector is used during memory page swap.

ABZmonPPC need some vector set to work correctly. The TRAP #15exception is needed to set 68K break point. The Line A exception is neededto enter to the debugger by calling _Debugger or _DebugStr. Stepping isdone via the Trace exception, and Line A is also used to step Mac OStoolbox procedure. NMI exception must be set if you want use the hardwareprogrammer switch button on some Mac.

Bug Report

ABZmonPPC has been tested on PowerMac 6100, Performa 6200 and Quadra950 with Apple PowerPC 610 upgrade card. If you cannot correctly installABZmonPPC or if you find any bug, please, leave me a message (the kind ofcomputer you use, when this bug appears,...).

CompuServe: [72467,2770]
Internet: 72467.2770@compuserve.com

Alain Birtz
650 Grand St-Charles,
St-Paul d’Abbotsford
P.Q., Canada, J0E-1A0

Table of contents

ABZmonPPC folder 	   2
Installation 	   2
Presentation 	   3
How the debugger is invoked 	   4
ABZmonPPC graphic interface 	   5
The active window 	   6
The default address 	   6
Debugger mode: PowerPC or 68K 	   7
Dialog 	   8
MAIN menu 	   9
CONTROL menu 	  10
Open menu 	  12
SEARCH menu 	  15
MON SPY menu 	  18
STEPSPY menu 	  20
STOP menu 	  21
TRACE menu 	  24
BREAK menu 	  26
MISC menu 	  31
The windows 	  33
Disassembler window 	  34
Dump window 	  36
Register window 	  37
Condition register window 	  39
Floating-point register window 	  40
Break point window 	  41
Message window 	  43
Clipboard window 	  44
Process window 	  45
File selector window 	  46
Text viewer window 	  47
Context window 	  48
68K DIS window 	  48
68K REG window 	  50
The calculator 	  50
The JB addresses 	  52
The JB conditions 	  54
The RTS command 	  55
The peril of Trace in MixedMode 	  59
DebugNum 	  60
Re-initialisation of DebugNum 	  61
ABZmonPPC special keys 	  62
Internal variables (PowerPC) 	  63
Internal variables (68K) 	  71
Bug Report 	  72